Implementation Plan: #127 — preserveScrollOnWrite

Goal

Add a minimal, opt-in terminal option that preserves the user’s scrolled-up viewport during streaming writes, while keeping the current “snap back to bottom on write” behavior as the default.

Target behavior:

• preserveScrollOnWrite omitted or false: current behavior remains — if Terminal.write() is called while viewportY !== 0, the terminal scrolls back to the bottom.
• preserveScrollOnWrite: true: if the user is scrolled up when Terminal.write() adds new scrollback lines, adjust the viewport offset by the scrollback growth so the same historical text remains visible instead of snapping to the bottom.

Advisor review status

• Reviewed with the advisor after the initial draft.
• Required revisions were incorporated: use signed scrollback delta, preserve robust fallback to existing snap-to-bottom behavior, stabilize smooth-scroll-sensitive tests, and add explicit onScroll coverage.
• Second advisor review approved the plan as implementation-ready; remaining polish notes were incorporated into the final plan.

Verified repo context

From focused read-only exploration:

• lib/interfaces.ts
  • ITerminalOptions is the public options interface that should receive the new optional boolean option.
• lib/terminal.ts
  • The Terminal constructor builds a defaulted baseOptions object from ITerminalOptions values.
  • writeInternal(data, callback) synchronously writes to the Ghostty WASM terminal, processes terminal responses, invalidates link cache, and currently calls scrollToBottom() whenever viewportY !== 0.
  • Relevant state/helpers include:
    • this.viewportY: current viewport offset from bottom; 0 means live bottom, values > 0 mean scrolled into history.
    • this.targetViewportY: smooth-scroll target that should stay in sync when manually changing viewportY.
    • this.getScrollbackLength(): current WASM scrollback length.
    • this.scrollEmitter.fire(Math.floor(this.viewportY)): existing scroll event mechanism.
    • this.showScrollbar() / existing scrollbar helpers: should be used consistently with current scroll paths when the preserved viewport changes.
    • this.scrollToBottom(): existing default snap-to-bottom behavior.
• lib/scrolling.test.ts
  • Existing scrolling tests use createIsolatedTerminal() from lib/test-helpers.ts, create a DOM container in beforeEach, open the terminal, and dispose/remove it in afterEach.
  • Useful test APIs: terminal.write(), terminal.scrollLines(), terminal.viewportY, and terminal.getScrollbackLength().
• Interactive dogfooding surface:
  • demo/scrollbar-test.html is the most direct browser surface for scroll behavior.
  • Vite must be used for browser demos because the demos import TypeScript modules directly.

Scope

In scope

1. Add preserveScrollOnWrite?: boolean to the terminal options API.
2. Default the option to false for backward compatibility.
3. Change Terminal.write() / writeInternal() scroll handling so the opt-in mode preserves scrolled-up content across writes.
4. Add focused tests for default behavior, opt-in behavior, no-growth writes, and runtime option toggling.
5. Run repository validation and manually dogfood the interactive behavior with reviewable screenshots/recording.

Out of scope

• Do not change Ghostty WASM parser behavior.
• Do not redesign scrolling, smooth-scroll animation, renderer dirty tracking, selection, scrollbar styling, or PTY behavior.
• Do not change the default auto-scroll behavior.
• Do not commit dogfooding-only demo controls or scratch artifacts unless explicitly requested.
• If an unrelated bug/flaky behavior is discovered, do not fix it in this task. Search existing issues first; if no match exists, create/comment on a separate needs-triage issue with evidence, then return to Could the automatic scrollToBttom() behaviour made to be configurable/togglable? #127.

Implementation phases

Phase 1 — Add the public option

Files:

• lib/interfaces.ts
• lib/terminal.ts

Steps:

1. Add the optional property to ITerminalOptions:

   preserveScrollOnWrite?: boolean;

2. In the Terminal constructor’s default/base options object, add:

   preserveScrollOnWrite: options.preserveScrollOnWrite ?? false,

3. Keep naming exactly preserveScrollOnWrite to match the issue, triage recommendation, and external fork precedent.

4. Do not add aliases or additional configuration knobs.

Quality gate after Phase 1:

• Run bun run typecheck if feasible at this point, or defer until tests are added if implementation is still mid-edit.

Phase 2 — Preserve scrolled-up viewport during writes

File:

• lib/terminal.ts

Recommended algorithm in writeInternal:

1. After this.assertOpen() and before this.wasmTerm!.write(data), capture:

   const savedViewportY = this.viewportY;
   const savedTargetViewportY = this.targetViewportY;
   const savedScrollbackLength = this.getScrollbackLength();

2. Leave the existing write pipeline intact:

   • WASM write(data) remains synchronous.
   • Existing terminal response processing remains in the same relative order.
   • Existing bell handling, link-cache invalidation, title detection, callbacks, and refresh/render scheduling remain unchanged.

3. Replace only the unconditional post-write auto-scroll block with scoped conditional behavior:

   if (this.options.preserveScrollOnWrite && savedViewportY > 0) {
     const newScrollbackLength = this.getScrollbackLength();
     const scrollbackDelta = newScrollbackLength - savedScrollbackLength;
     const nextViewportY = Math.max(
       0,
       Math.min(savedViewportY + scrollbackDelta, newScrollbackLength),
     );
     const nextTargetViewportY = Math.max(
       0,
       Math.min(savedTargetViewportY + scrollbackDelta, newScrollbackLength),
     );
   
     if (nextViewportY !== this.viewportY || nextTargetViewportY !== this.targetViewportY) {
       this.viewportY = nextViewportY;
       this.targetViewportY = nextTargetViewportY;
       this.scrollEmitter.fire(Math.floor(this.viewportY));
       if (newScrollbackLength > 0) {
         this.showScrollbar();
       }
     }
   } else if (this.viewportY !== 0) {
     this.scrollToBottom();
   }

4. Use the signed scrollback delta from the before/after measurements, then clamp. Do not mask negative deltas with Math.max(0, delta): unusual write data may clear or reduce scrollback, and the signed-delta formula keeps viewportY within valid bounds while matching the issue brief.

5. Keep the implementation minimal. Include a local defensive assertion/comment only if it documents a repository-confirmed invariant; do not turn escape-sequence behavior such as scrollback clearing into unrelated user-facing error handling.

6. Keep targetViewportY synchronized with viewportY; otherwise the existing smooth-scroll animation can pull the viewport back toward a stale target.

7. Clamp to the new scrollback length so the viewport never points beyond available history, especially when the configured scrollback limit has been reached.

8. If preserveScrollOnWrite is true but the user is at the bottom (savedViewportY === 0), do not adjust upward. The live bottom should continue showing new output. The else if (this.viewportY !== 0) fallback still preserves default snap-to-bottom behavior if processing somehow leaves the viewport nonzero outside the opt-in scrolled-up path.

Quality gate after Phase 2:

• Run the focused scrolling tests once they exist: bun test lib/scrolling.test.ts.
• If the focused suite exposes pre-existing unrelated failures, capture evidence and keep Could the automatic scrollToBttom() behaviour made to be configurable/togglable? #127 changes scoped.

Phase 3 — Add tests

File:

• lib/scrolling.test.ts

Add a focused suite such as describe('preserveScrollOnWrite', () => { ... }) using the existing createIsolatedTerminal() pattern. For deterministic assertions, prefer setting smoothScrollDuration: 0 directly in these new tests if the option works with the existing helper; otherwise wait for the smooth-scroll animation to settle before asserting viewportY / emitted scroll values.

Required tests:

1. Default behavior remains snap-to-bottom

   • Create a terminal without preserveScrollOnWrite.
   • Write enough lines to create scrollback.
   • scrollLines(-N) and assert viewportY === N.
   • Write one more line.
   • Assert viewportY === 0.

2. Opt-in mode preserves viewport across scrollback growth and emits onScroll

   • Create a terminal with { preserveScrollOnWrite: true }.
   • Register terminal.onScroll((value) => ...) before the preserving write.
   • Write enough lines to create scrollback.
   • Scroll up by N lines and record viewportY and getScrollbackLength().
   • Clear/ignore emissions caused by the setup scrollLines() call so the assertion targets the preserving write.
   • Write one or more newline-terminated lines.
   • Record the new scrollback length.
   • Assert viewportY === oldViewportY + (newScrollbackLength - oldScrollbackLength), clamped to the new scrollback length.
   • Assert the final onScroll emission for the preserving write matches Math.floor(terminal.viewportY).
   • If the existing test helpers expose stable visible-row text, also assert the top visible row text is unchanged before and after the write.

3. Opt-in mode does not move viewport when write creates no scrollback growth

   • Create with { preserveScrollOnWrite: true }.
   • Populate scrollback and scroll up.
   • Write data that does not add a new line / does not grow scrollback.
   • Assert viewportY remains unchanged.

4. Runtime option toggle works

   • Create a default terminal and verify the default snap-to-bottom behavior.
   • Set terminal.options.preserveScrollOnWrite = true.
   • Scroll up again, write one line, and verify preservation behavior.
   • This confirms the option proxy/defaulted options object participates in live behavior.

Test hygiene:

• Dispose terminals and remove containers in afterEach or local try/finally.
• Prefer deterministic row counts and small terminal dimensions so expected scrollback deltas are easy to reason about.
• Keep assertions focused on Could the automatic scrollToBttom() behaviour made to be configurable/togglable? #127; do not rewrite existing scrolling tests unless required for integration.

Quality gate after Phase 3:

bun test lib/scrolling.test.ts

Phase 4 — Full validation

Run the repository’s normal gates before claiming the implementation is done:

bun run fmt
bun run lint
bun run typecheck
bun test
bun run build

If bun test hangs after printing successful results, record the printed pass/fail summary and terminate only after confirming the test suite completed. If validation fails for an unrelated pre-existing reason, capture the exact command, failure, and why it is out of scope.

Phase 5 — Dogfooding and reviewable evidence

Goal: demonstrate the behavior in a real browser terminal surface and produce evidence reviewers can inspect.

Setup:

1. Install dependencies if needed:

   bun install

2. Start Vite, not a plain static file server:

   bun run dev

3. Use browser automation with the agent-browser skill or equivalent Playwright flow to open a same-origin page, preferably:

   http://localhost:8000/demo/scrollbar-test.html
   

Dogfood procedure:

1. Default mode evidence

   • Create or use a demo terminal with default options.
   • Populate scrollback with many numbered lines.
   • Scroll up until older numbered lines are visible.
   • Trigger a background write, for example by evaluating term.write('background line\r\n') in the page context or using an existing demo control.
   • Verify it snaps to the bottom.
   • Capture a screenshot before the write and after the snap.

2. Opt-in mode evidence

   • Use the same page context to set term.options.preserveScrollOnWrite = true, or instantiate a second terminal with { preserveScrollOnWrite: true } from /lib/terminal.ts in the browser page.
   • Populate scrollback with numbered lines.
   • Scroll up and note the visible top line.
   • Trigger several background writes.
   • Verify the visible historical text remains stable while the scrollbar thumb/position updates.
   • Capture before/after screenshots and a short screen recording showing multiple writes without snapping to bottom.

3. Evidence handling

   • Save screenshots/recordings outside the checkout, for example under /tmp/ghostty-web-127-dogfood/.
   • Attach the final screenshots/recording to the implementation summary or PR using the available attachment flow.
   • Do not commit temporary dogfood pages, scripts, screenshots, or videos.

Suggested evidence checklist:

• default-before-write.png: scrolled-up viewport before a default write.
• default-after-write.png: viewport snapped to live bottom after default write.
• preserve-before-writes.png: scrolled-up viewport with opt-in enabled.
• preserve-after-writes.png: same visible content after several background writes.
• preserve-scroll-on-write.webm or equivalent short recording demonstrating repeated writes.

Acceptance criteria

1. ITerminalOptions includes preserveScrollOnWrite?: boolean.
2. Terminal defaults preserveScrollOnWrite to false.
3. With the default setting, writing while scrolled up still scrolls to the bottom.
4. With preserveScrollOnWrite: true, writing while scrolled up preserves the visible historical content by adjusting viewportY by scrollback growth and clamping to available scrollback.
5. Opt-in preservation keeps targetViewportY synchronized so smooth scrolling does not undo the adjustment.
6. onScroll subscribers are notified when preservation changes the viewport, and scrollbar visibility/position is updated consistently with existing scroll behavior.
7. Tests cover default behavior, opt-in preservation, onScroll emission during preservation, no-scrollback-growth writes, and runtime toggling through terminal.options.
8. Focused and full validation commands pass, or any blocker is reported with exact command output and scope assessment.
9. Manual dogfooding produces reviewable screenshots and a short recording for default vs opt-in behavior.

Risks and mitigations

• Risk: Scrollback length can fail to grow for writes that still visually affect the screen.
  • Mitigation: Only adjust by measured scrollback delta. This preserves the intended streaming-output case without inventing broader viewport semantics.
• Risk: Smooth-scroll animation target fights the preserved viewport.
  • Mitigation: Update targetViewportY alongside viewportY.
• Risk: Scrollback limit drops old lines.
  • Mitigation: Clamp to the new scrollback length. Do not attempt to preserve content no longer retained by WASM.
• Risk: Tests depend on exact WASM scrollback behavior.
  • Mitigation: Derive expected deltas from getScrollbackLength() before/after writes rather than assuming every write produces exactly one scrollback line.
• Risk: Dogfooding requires page access to a terminal instance.
  • Mitigation: Prefer browser-page evaluation against the Vite-served app; if the demo does not expose term, instantiate a temporary terminal in page context via await import('/lib/terminal.ts') rather than committing demo-only controls.